---
title: 升级 Astro
description: 学习如何升级 Astro
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Version from '~/components/Version.astro';

本指南涵盖了如何更新你的 Astro 版本及相关依赖、如何了解从一个版本到下一个版本发生了什么变化，以及如何理解 Astro 的版本系统和相应的文档更新。

## 有什么变化？
Astro 的最新版本是 <Version pkgName="astro" />。

你可以在 [Astro 的更新日志](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) 中找到所有变化的详尽列表，并且在我们的[升级指南](#升级指南)中找到升级到每个新的[主要版本](#主要变更)的重要指导。

## 升级到最新版本

使用你的包管理器，通过一个命令更新你的项目中的 Astro 及所有官方集成到最新版本：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 同时升级 Astro 及其官方集成
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 同时升级 Astro 及其官方集成
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 同时升级 Astro 及其官方集成
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>


### 手动升级

要手动将 Astro 及其集成更新到当前版本，请使用适合你的包管理器的相应命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 示例：将 Astro 及其 React 和 Partytown 的集成升级
  npm install astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 示例：将 Astro 及其 React 和 Partytown 的集成升级
  pnpm add astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 示例：将 Astro 及其 React 和 Partytown 的集成升级
  yarn add astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
</PackageManagerTabs>

### 安装特定版本号

要安装特定的 [Astro 版本](https://www.npmjs.com/package/astro?activeTab=versions) 或集成，请使用适合你的包管理器的相应命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
</PackageManagerTabs>


## 文档更新

每次 [次要版本发布](#次要变更) 和 [主要版本发布](#主要变更) 时，本文档都会进行更新。当添加新功能或现有用法发生变化时，文档将更新以反映 **Astro 的当前行为**。如果你的项目没有更新，那么你可能会注意到一些行为与最新的文档不匹配。

新功能将添加到文档中，并带有添加它们的特定版本号。这意味着，如果你没有更新到 Astro 的最新版本，一些文档中的功能可能无法使用。始终检查 `Added in:` 版本号，并确保你的项目在尝试使用新功能之前已经更新。

如果你还没有升级到 Astro 的最新主要版本，你可能会遇到 Astro 文档和你的项目行为之间的重大差异。我们强烈建议尽快升级到 Astro 的当前主要版本。早期版本的代码和文档都不再受支持。

### 升级指南

在每次[主要版本发布](#主要变更)之后，你会找到一个**升级指南**，其中包含重要变更的信息和升级项目代码的指示。

Astro 的主要文档页面始终**准确反映 Astro 最新发布版本的内容**。它们不会描述或比较以前版本的工作方式，也不会突出显示更新或更改的行为。

请参阅下面的升级指南，了解变更的解释，将新版本与旧版本进行比较。升级指南包括所有可能需要你更改自己代码的内容：重大变更、弃用、功能移除和替换以及更新的使用指导。Astro 的每次变更都包括一个“我应该做什么？”部分，以帮助你成功更新项目代码。


- [升级到 v5 版本](/zh-cn/guides/upgrade-to/v5/)
- [升级到 v4 版本](/zh-cn/guides/upgrade-to/v4/)
- [升级到 v3 版本](/zh-cn/guides/upgrade-to/v3/)
- [升级到 v2 版本](/zh-cn/guides/upgrade-to/v2/)
- [升级到 v1 版本](/zh-cn/guides/upgrade-to/v1/)

### 旧版本文档（不再维护）

Astro 的旧版本文档不再进行维护，但可以作为静态快照访问。如果你无法升级你的项目，但仍希望查阅指南和参考资料，请使用这些版本的文档：

- [不再维护的 v4.16.17 快照](https://v4.docs.astro.build/zh-cn/getting-started/)
- [不再维护的 v3.6.3 快照](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/)
- [不再维护的 v2.10.15 快照](https://deploy-preview-4405--astro-docs-2.netlify.app/zh-cn/getting-started/)


## 语义化版本控制

Astro 尽可能地遵循 [语义化版本控制](https://semver.org/)，这是一套开发者用来决定如何为发布分配版本号的规则。语义化版本遵循一个可预测的模式，以通知用户从一个版本到下一个版本可以期待的变化类型。

语义化版本控制强制执行 `X.Y.Z` 的模式用于软件版本号。这些值分别代表 **主要更新 (X)**、**次要更新 (Y)** 和 **补丁更新 (Z)**。

### 补丁更改

补丁更改是最小干扰的更改。它们不会改变你使用 Astro 的方式，当你更新时也不需要对你的代码进行任何更改。

当 Astro 发布一个“补丁”版本时，最后的数字会增加。（例如，`astro@4.3.14` -> `astro@4.3.15`）

可能出于以下原因发布补丁：

- 不改变 Astro 功能的内部变更：
  - 重构
  - 性能提升
  - 增加或改变测试覆盖率
  - 与声明的文档和预期行为保持一致
- 日志和错误消息的改进。
- 发布失败后的重新发布。

补丁更改还包括**大多数 bug 修复**，即使在用户利用现有的非预期或不希望的行为的情况下也是如此。


### 次要变更

次要版本主要引入了你可能想尝试的新功能和改进，但不需要对你的代码进行任何更改。在次要版本中，一些现有功能可能也会被**弃用**（在未来的版本中标记为删除，同时继续运行），为你提供了准备最终移除它们的机会。

次要版本包括如下变更：

- 现有功能/选项的**弃用**，并警告它们将在即将到来的主要版本中被移除。
- 引入新的功能。
- 在集成钩子中引入新的选项。
- 在 `astro/app` 中引入新的功能，特别是用于创建新的适配器。

次要版本也可能同时包括较小的，补丁级别的变更。

### 主要变更

主要版本将包括对至少一些现有代码的重大更改。这些重大更改总是记录在 Astro 的 ["升级到 vX 版本" 指南](#升级指南) 中。

主要版本允许 Astro 不仅对内部逻辑进行重大更改，还对预期的行为和使用进行更改。文档将仅更新以反映最新版本，而**静态的、不再维护的旧文档快照**可作为尚未升级的旧项目的历史记录。

主要版本包括的更改如下：

- 移除之前已弃用的功能。
- 现有功能的更改。
- 集成钩子中现有选项的更改。
- 在 `astro/app` 中现有选项和功能的更改，特别是用于创建新适配器的。

主要版本也可能包括一些非破坏性的更改和改进，这些通常会在次要或补丁版本中单独发布。

### 异常情况

- **实验性功能**。在不遵守语义版本控制的情况下发布的 Astro 版本，可以让 Astro 开发者在开发实验性功能时拥有最大的灵活性，甚至可以在开发过程中从根本上改变方向。因此，这些功能的行为可能会导致微小的更改和补丁更改。

  这些功能通常伴随着一个持续进行的、公开的[请求考虑（RFC）第 3 阶段](https://github.com/withastro/roadmap#stage-3-rfc--development)。预期 beta 用户会关注更新，并在讨论中提前反馈，以帮助指导这些功能的开发。

  一旦这些功能结束了它们的实验期，它们将遵循正常的语义化版本控制合约。

- **文档的改进**（例如，参考和错误消息）。它们是为 `docs` 仓库从源代码构建的。这允许 Astro 在文档源内容存储在主 `astro` 仓库的情况下，快速更新文档修复和改进。

### Node.js 支持和升级策略

#### 支持

- Astro 支持 [**最近的 _Maintenance_ LTS** 版本的 Node.js](https://nodejs.org/en/about/previous-releases#release-schedule)。
- Astro 支持 [**当前的 _Active_ LTS** 版本的 Node.js](https://nodejs.org/en/about/previous-releases#release-schedule)。
- Astro 也支持 Node.js 的奇数版本。

#### 升级

以下规则定义了 Astro 何时可能弃用、删除或增加对 Node.js 版本的支持：

- 当 Node.js 发布下一个偶数版本时，可以弃用和/或删除 Node.js 的奇数版本。在 Astro 核心团队决定的合理的延长支持期之后，这种变化可能在 Astro 的**次要**版本中发生。
- 升级最低 **_Maintenance_ LTS**（在相同的主要版本范围内，例如，从 `v18.14.*` 到 `v18.20.*`）版本的 Node.js 可以在 Astro 的**次要**版本中发生。
  - 安全例外：如果 Node.js 中的安全漏洞被披露并修复，且**影响到 Astro**，核心团队可以在**补丁**版本中提升最低的 **_Maintenance_ LTS** 版本。
- 只有在 Astro 的主要版本中，才会升级 Node.js 的次要或主要版本（**不是** Maintenance LTS）。
  - 安全例外：如果 Node.js 中的安全漏洞被披露并修复，且**影响到 Astro**，核心团队可以在**次要**版本中提升最低版本。

### 延长维护

核心团队将为上一个主要版本**仅提供安全修复的**延长维护。这意味着如果当前的主要版本是 `v4.*`，核心团队将回移安全修复并发布一个新的 `v3.*` 版本。
